Skip to content

docs(#911): add build and validation workflow to CLAUDE.md - #912

Open
fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/911-document-precommit-workflow
Open

docs(#911): add build and validation workflow to CLAUDE.md#912
fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/911-document-precommit-workflow

Conversation

@fullsend-ai-coder

@fullsend-ai-coder fullsend-ai-coder Bot commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Summary

Changes

CLAUDE.md — added three subsections:

  • Script bundling: Documents the .src.sh → .sh bundle architecture and the make script-build command.
  • Pre-commit: Documents pre-commit run --all-files requirement, lists which shellcheck codes are excluded (SC1091, SC2001, SC2016) and which are blocking (SC2030, SC2031, SC2034, SC2153), and explains the # shellcheck disable=SC2153 pattern for variable name clashes.
  • Tests: Documents make test as the test command.

Testing

  • Verified the documented shellcheck exclusions match .pre-commit-config.yaml (args: ["-x", "-e", "SC1091,SC2001,SC2016"]).
  • Verified make script-build target exists in Makefile and rebuilds all 12 .src.sh files.
  • Verified make test is the correct test command.
  • Pre-commit could not run in the sandbox (network policy blocked hook environment installation).

Closes #911

Post-script verification

  • Branch is not main/master (agent/911-document-precommit-workflow)
  • Secret scan passed (gitleaks — d491a976c945a03a3a46e96b64405cc7e168a476..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

@fullsend-ai-coder
docs(#911): add build and validation workflow to CLAUDE.md
d2b79c9 
Document the mandatory pre-commit and script-build workflow that
agents must follow when modifying shell scripts in this repo:

- Run `make script-build` after changing any `.src.sh` source file
  or `scripts/lib/*.lib.sh` library to regenerate bundled `.sh`
  artifacts.
- Run `pre-commit run --all-files` before committing and fix all
  violations, including info-level shellcheck codes (SC2030,
  SC2031, SC2034, SC2153) that are not excluded by the repo config.
- Stage both the source `.src.sh` and generated `.sh` together.
- Use `# shellcheck disable=SC2153` for variable name clashes
  rather than renaming variables.
- Run `make test` for the full test suite.

This addresses the root cause of 5 failed agent runs on #860/#872
where agents had no way to discover these repo-specific build and
lint requirements.

Note: pre-commit could not run in the sandbox (network policy
blocked hook environment installation). The post-script runs an
authoritative pre-commit check on the runner.

Closes #911
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team as a code owner August 21, 2026 01:18
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 21, 2026 •
edited
Loading

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 1:20 AM UTC · Completed 1:32 AM UTC

Commit: d2b79c9 · View workflow run →

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 21, 2026

Copy link
Copy Markdown

Review

Findings

Medium

  • [technical documentation accuracy] CLAUDE.md:20 — The documentation states "The check-bundle pre-commit hook verifies that committed bundles match the output of make script-build and will reject stale bundles." However, check-bundle is not registered in .pre-commit-config.yaml — it is a Makefile target (make check-bundle) invoked only in CI via .github/workflows/script-test.yml. Calling it a "pre-commit hook" is factually incorrect and could mislead agents into believing it runs automatically at commit time when it actually only runs in CI.
    Remediation: Change to "CI runs make check-bundle to verify that committed bundles match the output of make script-build and will reject stale bundles."

  • [protected-path] CLAUDE.md — This PR modifies CLAUDE.md, which is a protected governance file. The change is authorized by issue CLAUDE.md should document pre-commit and script-build validation workflow #911 and the PR description explains the rationale. Human approval is always required for protected-path changes, regardless of context.

Low

  • [scope-creep] CLAUDE.md:45 — The "Tests" subsection documenting make test is not part of the scope authorized by issue CLAUDE.md should document pre-commit and script-build validation workflow #911, which specifically covers script bundling, pre-commit validation, co-staging, and shellcheck disable patterns. The addition is minor (3 lines) and harmless.
    Remediation: Consider removing the "Tests" subsection if strict scope adherence is desired, though its inclusion is a trivially small addition of useful information.

@fullsend-ai-review fullsend-ai-review Bot added the requires-manual-review Review requires human judgment label Aug 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

ready-for-review requires-manual-review Review requires human judgment

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

CLAUDE.md should document pre-commit and script-build validation workflow

0 participants